Quizzes

A comprehensive system for managing quizzes, question banks, attempts, and grading workflows with modular, testable components.

🗂️ Folder Structure

quizzes/
├── abilities/                   # CASL policies for quiz, question, attempt, and bank permissions
│   ├── attemptAbilities.ts
│   ├── questionAbilities.ts
│   ├── questionBankAbilities.ts
│   └── quizAbilities.ts
├── classes/                      # DTO validators and response transformers
│   ├── validators/               # Input schemas: QuizValidators, QuestionValidators, AttemptValidators
│   └── transformers/             # Output schemas and mappers: QuizResponse, QuestionData, AttemptResult
├── controllers/                  # API endpoints
│   ├── QuizController.ts         # Create, retrieve, update, delete quizzes
│   ├── QuestionBankController.ts # Manage question banks and import/export
│   ├── QuestionController.ts     # CRUD for individual questions
│   ├── AttemptController.ts      # Handle quiz attempts, submissions, and retrieval
├── interfaces/                   # TypeScript contracts
├── question-processing/          # Pluggable question logic
│   ├── QuestionProcessor.ts      # Core pipeline for rendering and grading
│   ├── graders/                  # Individual grading strategies (multiple choice, free text)
│   ├── renderers/                # Question renderers for different formats
│   ├── tag-parser/               # Parses custom tags in question text
│   └── validators/               # Business-rule validators for question consistency
├── services/                     # Business logic
│   ├── QuizService.ts            # Orchestrates quiz creation, versioning, and deletion
│   ├── QuestionBankService.ts    # Bank import, export, and search
│   ├── QuestionService.ts        # Manages individual question lifecycle
│   └── AttemptService.ts         # Evaluates submissions, calculates scores, tracks progress
├── utils/                        # Shared functions (e.g., pagination, randomization)
├── container.ts                  # Binds controllers, services, repos, and abilities using InversifyJS
├── types.ts                      # DI symbols for all components in module
└── tests/                        # Unit and integration tests

🎯 Component Responsibilities

• Controllers: Expose RESTful endpoints; validate input via DTOs; enforce CASL policies via @Authorized and ability decorators.
• Services: Contain core business workflows—quiz lifecycle, bank management, question operations, attempt grading and scoring.
• Repositories: Abstract MongoDB operations for quizzes, questions, banks, and attempts; support transactions and pagination.
• Abilities: Define fine-grained access rules for CRUD operations and attempt submissions.
• Question Processing: Modular pipeline to render questions, parse custom tags, validate business rules, and apply grading strategies.
• Interfaces & Types: Ensure type-safe contracts for grading algorithms, repository methods, and DTOs.
• Dependency Injection: container.ts binds interfaces to implementations using Inversify’s @injectable and @inject, promoting loose coupling and easy testing.

🔁 Interaction Flow

1. Quiz Definition: Instructors create quizzes and attach question banks via QuizController.
2. Question Management: Questions authored via QuestionController, validated, and stored in banks.
3. Attempt Lifecycle: Students initiate attempts (AttemptController), answers processed through AttemptService using QuestionProcessor.
4. Scoring & Feedback: Graders compute scores; results persisted and accessible to users.
5. Integration: Module interacts with Auth for user identity, Users for progress tracking.